﻿#region Header
// ------------------------ Licence / Copyright ------------------------
// 
// ScrumTable for Scrum Meeting Support
// Copyright © HSR - Hochschule für Technik Rapperswil
// All Rights Reserved
// 
// Author:
//  Michael Gfeller Silvan Gehrig Patrick Boos
// 
// ---------------------------------------------------------------------
#endregion

#region Usings

using System;
using ScrumTable.Common;
using ScrumTable.Common.Security;

#endregion

namespace ScrumTable.DL.Data.Common
{
    /// <summary>
    /// Specifies the state of a connection to an external
    /// system and data provider.
    /// </summary>
    [Flags]
    public enum ConnectionState
    {
        /// <summary>
        /// A connection to an external system has not been established.
        /// </summary>
        Disconnected = 0,

        /// <summary>
        /// A connection is established.
        /// </summary>
        Connected = 1,

        /// <summary>
        /// The connection link is broken, connection failed.
        /// </summary>
        LinkBroken
    }

    /// <summary>
    /// Represents the data connection which is used to login and logout
    /// </summary>
    public interface IDataConnection : IDisposableObject
    {
        #region Properties
        //--------------------------------------------------------------------
        // Properties
        //--------------------------------------------------------------------

        /// <summary>
        /// Returns true if the external system has been connected and its data
        /// has been loaded.
        /// </summary>
        bool IsConnected { get; }

        /// <summary>
        /// Gets the current connection state.
        /// </summary>
        ConnectionState ConnectionState { get; }

        /// <summary>
        /// Gets the connection information which are provided by the user
        /// and used to establish a connection to the external data services.
        /// </summary>
        ConnectionInformationManager ConnectionManager { get; }

        /// <summary>
        /// Gets the hint to the connection location.
        /// </summary>
        string ConnectionMoniker { get; }

        #endregion

        #region Methods
        //--------------------------------------------------------------------
        // Methods
        //--------------------------------------------------------------------

        /// <summary>
        /// Connects to the server instance. Make sure you disconnect from the
        /// server after you finished your work with the data connection.
        /// </summary>
        /// <param name="connectionCtx">Specifies the connection context which provides information about the end system and the user.</param>
        /// <param name="callback">Specifies the callback used to retrieve the connection state. The callback value is of type DataResult.</param>
        /// <param name="dataMoniker">Specifies a hint (moniker) to the data location. This must be supported by the underlying driver.</param>
        void Connect(ConnectionInformationManager connectionCtx, AsyncCallback callback, string dataMoniker);

        /// <summary>
        /// Changes the user and stores its changes to the back end system.
        /// </summary>
        /// <param name="credentialsObject">Specifies the login credential information object.</param>
        /// <param name="callbackEvent">Specifies the callback which is fired after the
        /// process has been completed. The callback is of type ICancellableDataResult
        /// and its Data property contains true, if all changes have been accepted.</param>
        void ChangeUser(IDataObject credentialsObject, AsyncCallback callbackEvent);

        /// <summary>
        /// Changes the user after the latests changes have been stored to the back end system.
        /// </summary>
        /// <param name="credentialsObject">Specifies the login credential information object.</param>
        void ChangeUser(IDataObject credentialsObject);

        /// <summary>
        /// Disconnects from a connected server instance and clears all
        /// data in the current data context. After a disconnect, you can
        /// reconnect using the connect method.
        /// </summary>
        void Disconnect();

        #endregion

        #region Events
        //--------------------------------------------------------------------
        // Events
        //--------------------------------------------------------------------

        #endregion
    }
}